<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Dialog</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="javascript" src='../links.js' type="text/javascript"></script>
</head>

<body>

<h1>Dialog</h1>
<div class=navbar>
<a href="../index.html">main</a> |
<a href="index.html">Dialog API</a><br>
</div>

<div class=shortdescr>
The <dfn>Dialog</dfn> function shows a dialog.
</div>

<pre class=syntax>
int WINAPI Dialog(
  int PluginNumber,
  int X1,
  int Y1,
  int X2,
  int Y2,
  const char *HelpTopic,
  struct FarDialogItem *Item,
  int ItemsNumber
);
</pre>

<h3>Parameters</h3>
<div class=descr>
  <div class=dfn>PluginNumber</div>
  <div class=dfndescr>Number of the plugin module. It is passed to the plugin in the <a href="../exported_functions/setstartupinfo.html">SetStartupInfo</a> function.</div>
  <div class=dfn>X1, Y1, X2, Y2</div>
  <div class=dfndescr>Dialog coordinates.
You can specify them explicitly or use <code>"Width x Height"</code> formula - in this case both <var>X1</var> and <var>Y1</var> must be set to -1, while
<var>X2</var> and <var>Y2</var> define dialog width and height respectively. In the latter case the dialog will be automatically centered on the screen.
<var>X2</var> and <var>Y2</var> parameters can't be less than zero.
</div>
  <div class=dfn>HelpTopic</div>
  <div class=dfndescr><a href="../language/helptopic.html">Help topic</a> associated with the dialog. It can be NULL if help is not required.
    </div>
  <div class=dfn>Item</div>
  <div class=dfndescr>Address of an array of <a href="structures/fardialogitem.html">FarDialogItem</a> structures. Each structure describes one dialog item.</div>
  <div class=dfn>ItemsNumber</div>
  <div class=dfndescr>Number of FarDialogItem structures.</div>
</div>

<h3>Return value</h3>
<div class=descr>This function returns either -1, if the user cancelled the dialog, or the index of the selected dialog item in the Item array.
</div>


<h3>Remarks</h3>
<div class=descr>
<p>
FAR transforms Item elements to its own internal structure before creating a dialog.
After dialog processing is over, Item elements array is adjusted according to changes made in
the progress of user work with the dialog.
</div>



<h3>Example</h3>
<div class=descr>
Example from the configuration dialog of TempPanel plugin:

<pre class=code>
int Config()
{
  struct <a href="../addons/structures/initdialogitem.html">InitDialogItem</a> InitItems []={
    DI_DOUBLEBOX,3,1,72,8,0,0,0,0,(char *)MConfigTitle,
    DI_CHECKBOX,5,2,0,2,0,0,0,0,(char *)MConfigAddToDisksMenu,
    DI_FIXEDIT,7,3,7,3,1,0,0,0,&quot;&quot;,
    DI_TEXT,9,3,0,3,0,0,0,0,(char *)MConfigDisksMenuDigit,
    DI_TEXT,5,4,0,4,0,0,DIF_BOXCOLOR|DIF_SEPARATOR,0,&quot;&quot;,
    DI_CHECKBOX,5,5,0,5,0,0,0,0,(char *)MConfigCommonPanel,
    DI_TEXT,5,6,0,6,0,0,DIF_BOXCOLOR|DIF_SEPARATOR,0,&quot;&quot;,
    <b>DI_BUTTON,0,7,0,7,0,0,DIF_CENTERGROUP,1,(char *)MOk,</b>
    DI_BUTTON,0,7,0,7,0,0,DIF_CENTERGROUP,0,(char *)MCancel
  };
  struct FarDialogItem DialogItems[sizeof(InitItems)/sizeof(InitItems[0])];
  . . .
  <a href="../addons/initdialogitems.html">InitDialogItems</a>(InitItems,DialogItems,
                   sizeof(InitItems)/sizeof(InitItems[0]));
  . . .
  int ExitCode=Info.Dialog(Info.ModuleNumber,
                  -1,-1,76,10,
                  &quot;TempCfg&quot;,DialogItems,
                  sizeof(DialogItems)/sizeof(DialogItems[0]));
  <b>if (ExitCode != 7)</b>
    return(FALSE);
. . .
}
</pre>
</div>

<div class=see>See also:</div><div class=seecont>
<a href="dialogex.html">DialogEx</a>,
<a href="../service_functions/index.html">service functions</a>,
<a href="../service_functions/message.html">Message</a>,
<a href="../addons/initdialogitems.html">InitDialogItems</a>
</div>

</body>
</html>